Coupon Stash v1.4 - User Guide
By: Team F09-1
| Contents | Section Number |
|---|---|
Introduction |
1 |
About This Document |
2 |
Quick Start |
3 |
Features
|
4 |
Keyboard Shortcuts
|
5 |
FAQ |
6 |
Command Summary |
7 |
Appendix |
8 |
Welcome to the Coupon Stash User Guide! Thank you so much for choosing Coupon Stash, the world’s most popular command-line coupon management desktop application*!
This guide will help you get started quickly, providing useful tips and hints along the way.
*as of April 2020
- 1. Introduction
- 2. About This Document
- 3. Quick Start
- 4. Features
- 4.1. Adding a coupon:
add - 4.2. Editing a coupon:
edit - 4.3. Deleting a coupon:
delete - 4.4. Listing coupons:
list - 4.5. Using a coupon:
used - 4.6. Viewing savings:
saved - 4.7. Archiving a coupon:
archive - 4.8. Unarchiving a coupon:
unarchive - 4.9. Locating coupons by name:
find - 4.10. Listing all expiring coupons:
expiring - 4.11. Sorting coupons:
sort - 4.12. Copying a coupon:
copy - 4.13. Sharing a coupon:
share - 4.14. Undoing the previous command:
undo - 4.15. Redoing the undone command:
redo - 4.16. Displaying a Month-Year on the calendar:
goto - 4.17. Displaying a Coupon:
expand - 4.18. Setting currency symbol:
setcurrency - 4.19. Viewing help:
help - 4.20. Clearing all entries:
clear - 4.21. Exiting the program:
exit - 4.22. Reminding of coupon expiry
- 4.23. Saving the data
- 4.1. Adding a coupon:
- 5. Keyboard Shortcuts
- 6. FAQ
- 7. Command Summary
- 8. Appendix
1. Introduction
Coupon Stash is meant for School of Computing (SoC) students and staff who enjoy managing their coupons with a desktop command-line interface. It is optimised for efficient usage in this aspect, while still offering a sleek, beautiful Graphical User Interface (GUI).
Jump to the Quick Start section to get started now. We sincerely hope you enjoy using Coupon Stash!
2. About This Document
This document introduces the features of Coupon Stash.
The following are symbols and formatting used in this document:
|
Tip
|
Tips are used to describe small features or techniques that may come in handy when using Coupon Stash! |
|
Warning
|
Warnings bring your attention to certain practices that may have unintended consequences! |
|
Note
|
Notes describe certain features or behaviour that may not be so obvious! |
Boxes like these contain useful information, for emphasis and easy reference!
-
Coupon Stash command words are formatted with
code blocks.
-
Blue, underlined words are links! Try clicking on the link on the left!
3. Quick Start
-
Ensure you have Java (version 11 or above) installed in your Computer.
-
Download the latest
CouponStash.jar. -
Copy the file to the folder you want to use as the home folder for your Coupon Stash.
-
Double-click the file to start the app. The GUI should appear in a few seconds. If nothing occurs, use the command
java -jar CouponStash.jaron your computer’s Command Line Interface (CLI) to open the file up. -
Type the command in the command box and press Enter to execute it.
-
Some example commands you can try:
-
list : lists all coupons
-
add:
add n/Domino’s Pizza Extra Large s/40% p/ILOVEDOMINOS e/30-4-2020 l/5 t/pizza t/delivery-
adds a coupon named Domino’s Pizza Extra Large to the Coupon Stash, with an expiry date of 30th April 2020, 40% savings with promo code ILOVEDOMINOS, and a limit of 5 usages.
-
-
delete:
delete 3: deletes the 3rd coupon shown in the current list -
exit : exits the app (your data will be saved automatically)
-
-
Refer to the Features section below for the details of each command.
4. Features
This section introduces the features of Coupon Stash. There are some examples
for you to try out in Coupon Stash too!
Also, take note of the general format of all the commands below!
|
Note
|
4.1. Adding a coupon: add
Adds a coupon. Some fields like name, expiry date and savings are
required.
Optional fields like promo code and tags may be provided as well.
Format: add n/NAME e/EXPIRY_DATE s/SAVINGS_OR_FREE_ITEM [sd/START_DATE] [r/REMIND_DATE] [p/PROMO_CODE] [c/CONDITIONS] [u/USAGE] [l/USAGE_LIMIT] [s/EXTRA_FREE_ITEMS]… [t/TAG]…
|
Tip
|
A coupon can have any number of tags (including 0) |
|
Note
|
If unspecified, the default remind date of a coupon will be set to 3 days before the expiry date. Go to Section 4.22, “Reminding of coupon expiry” to learn more about remind dates. |
Examples:
-
add n/McDonald’s McGriddles p/ILOVEMCGRIDDLES e/31-12-2020 s/$2 sd/1-4-2020 l/2 t/value t/savouryAdds a new Coupon:
-
add n/Grabfood s/40% e/30-4-2020 p/GRAB40 t/deliveryAdds a new Coupon:
|
Tip
|
If your coupon allows for unlimited usage, set the limit of the coupon to a
number less than 1! E.g. l/0
|
4.2. Editing a coupon: edit
Edits an existing coupon in the coupon book.
Format: edit INDEX [n/NAME] [e/EXPIRY_DATE] [sd/START_DATE] [r/REMIND_DATE] [p/PROMO_CODE] [c/CONDITION] [l/USAGE_LIMIT] [s/SAVINGS_OR_FREE_ITEMS]… [t/TAG]…
|
Note
|
Savings cannot be cleared in the same way as clearing tags, as a coupon must have at least 1 saving. |
|
Note
|
Remind date cannot be removed or cleared. Go to Section 4.22, “Reminding of coupon expiry” to learn more about remind dates. |
Examples:
-
edit 1 s/50%
Edits the savings of the 1st coupon to be 50% off. -
edit 2 n/The Deck Nasi Ayam Hainan t/
Edits the name of the 2nd coupon to be The Deck Nasi Ayam Hainan and clears all existing tags.
4.3. Deleting a coupon: delete
Deletes the specified coupon from the coupon stash.
Version 2.0 will bring new features like confirmation of coupons before they are deleted!
Also, a "recycle bin" is in the works for version 3.0, similar to the Recycle Bin in Microsoft Windows.
Format: delete INDEX
Examples:
-
list
delete 2
Deletes the 2nd coupon in the coupon stash. -
find rice
delete 1
Deletes the 1st coupon in the results of the find command.
4.4. Listing coupons: list
Shows a list of coupons in the coupon stash.
There are 3 types of lists:
-
List of active coupons
-
List of archived coupons
-
List of used coupons
Format: list [PREFIX]
|
Note
|
PREFIX can be left blank to list all active coupons. (coupons that are not
expired/ not fully used/ not archived)
|
Examples:
-
list
Shows a list of all active coupons -
list a/
Shows a list of all archived coupons -
list u/
Shows a list of all used coupons (but not fully used)
4.5. Using a coupon: used
Uses a coupon if its usage has yet to reached its limit.
Requires an original amount of purchase if the coupon has savings in a
percentage value.
Format: used INDEX or used INDEX MONETARY_AMOUNT
where MONETARY_AMOUNT is a number prefixed by a user-defined currency
symbol e.g. ($4.50, where the currency symbol is "$").
Examples:
-
used 1
Uses the first coupon in the coupon stash. -
used 1 $10.0
Uses the first coupon in the coupon stash, which also has a percentage savings. The total savings of the coupon will be calculated, and can be seen with the commandsaved.
4.6. Viewing savings: saved
Shows you how much you have saved by using coupons in Coupon Stash. There are three ways to use this command:
-
If just the word "saved" is entered, the total savings accumulated since you started using Coupon Stash will be shown.
Format:
saved -
If a specific date is given, Coupon Stash will show you savings earned only on that day.
Format:
saved d/DATE_TO_SHOW -
If a start date and end date are given, Coupon Stash will show you the total savings accumulated over all the dates between that start date and end date, inclusive of those dates as well.
Format:
saved sd/START_DATE e/END_DATE
Examples:
-
saved d/1-3-2020
A message will be displayed: You have saved $6.50 as well as earned 2x Brattby Bag on 1 March 2020. -
saved sd/1-5-2019 e/20-3-2020
A message will be displayed: You have saved $117.15 as well as earned 5x Brattby Bag, 7x Water Bottle, 12x Free Coffee, 1x Plush Toy between 1 May 2019 and 20 March 2020.
4.7. Archiving a coupon: archive
Archives a coupon when you want to keep a record of it, without cluttering your current stash of coupons.
|
Note
|
To view archived coupons, the user can run the list
a/ command to list all
archived coupons. Alternatively, the find command explained below will
search all archived coupons, thus displaying archives that match the supplied
keywords below unarchived coupons. Finally, the
expiring command will also
include all archived coupons that are expiring in its results.
Read the section on find and
expiring
respectively to find out more.
|
Format: archive INDEX
Examples:
-
archive 1
Archives the first coupon in the coupon stash.
|
Tip
|
To keep your coupons more organized, Coupon Stash will automatically archive your coupons once their usage limit has been reached, or when they have expired. |
4.8. Unarchiving a coupon: unarchive
Unarchive a coupon, thus bringing it back to your active coupons list.
|
Note
|
To unarchive a coupon, you have to make sure that the archived coupon is
visible in the coupon stash first. Read the section on the
archive command to find out the ways that
you can display archived coupons.
|
Format: unarchive INDEX
Examples:
-
unarchive 1
Unarchive the first coupon in the coupon stash.
4.9. Locating coupons by name: find
Find coupon(s) whose names contain any of the given keywords.
Format: find KEYWORD [MORE_KEYWORDS]…
|
Tip
|
For easy finding of coupons, include the store or brand name in your coupon name! |
Examples:
-
find ken
For example, coupons with these names would be returned: Ken Kitchen, KEN RIDGE Optical, ken you build a snowman.
4.10. Listing all expiring coupons: expiring
Shows a list of all your coupons expiring on a date or during a MonthYear.
Format: expiring e/EXPIRY_DATE or expiring my/MONTH_YEAR
Examples:
-
expiring e/11-9-2020
Shows you all the coupons that will expire on 11 September 2020. -
expiring my/9-2020
Shows you all the coupons that will expire during September 2020.
|
Note
|
The expiring command will include archived
coupons in its results too. Coupons that are expiring in the archives are
displayed below the non-archived matches.
|
4.11. Sorting coupons: sort
Sorts the coupons in CouponStash in ascending order. It is possible to sort by coupon name or expiry date.
|
Note
|
The sorting order will persist throughout the runtime of the program. The command will sort any coupons currently on screen, including archived coupons , if they are present on screen. Archived coupons will always appear below active coupons. |
Format: sort PREFIX
Examples:
-
sort n/
Sorts the coupon stash by name in ascending order. -
sort e/
Sorts the coupon stash by expiry date from earliest to latest.
4.12. Copying a coupon: copy
Copies a coupon as an add command to your
clipboard so that you can easily share it with your friends/ family!
Format: copy INDEX
|
Note
|
Examples:
-
list
copy 2
Copies the 2nd coupon in the coupon stash to anaddcommand and copies it to your clipboard. -
find chicken
copy 1
Copies the 1st coupon in the results of the find command to anaddcommand and copies it to your clipboard.
4.13. Sharing a coupon: share
Shares a coupon as a .png image file. Now you can post your coupons on
Instagram!
Format: share INDEX
|
Note
|
Image generated looks exactly like how a coupon shows up in the user interface. Below is a sample of how a shared coupon image looks like: |
Examples:
-
list
share 2
Shares the 2nd coupon in the coupon stash and save it as a.pngfile. -
find chicken
share 1
Shares the 1st coupon in the results of the find command and save it as a.pngfile.
4.14. Undoing the previous command: undo
Undo the most recent operation on the coupon stash. Only operations that change the coupons in the coupon stash can be undone.
Format: undo
|
Note
|
Changes to user preferences cannot be undone. |
Examples:
-
edit 1 r/ 25-12-2020
undo
Undo theeditcommand. Remind date of 1st coupon reverts back to its original value. -
delete 1
undo
Revert thedeletethat was performed. Deleted coupon is restored.
4.15. Redoing the undone command: redo
Redo the previously undone operation. This is akin to undoing an
undo.
Format: redo
Examples:
-
edit 1 r/ 25-12-2020
undo
redo
Un-undo theeditcommand. Remind date of 1st coupon is edited. value. -
delete 1
undo
redo
Un-undo thedeletecommand. 1st coupon is deleted.
4.16. Displaying a Month-Year on the calendar: goto
Goes to the specified Month-Year on the calendar.
Format: goto my/MONTH_YEAR
Example:
-
goto my/12-2020
Goes to December 2020 on the Calendar
4.17. Displaying a Coupon: expand
Displays a coupon in its own window, giving you a complete view of it.
Format: expand INDEX
Examples:
-
expand 1
Open the coupon at index 1 in a new window.
4.18. Setting currency symbol: setcurrency
Sets the currency symbol used in Coupon Stash. This will force Coupon Stash to reload all coupons to use the new symbol instead.
Format: setcurrency ms/NEW_MONEY_SYMBOL
Examples:
-
setcurrency ms/€
Sets the money symbol used in commands, as well as to display coupons' savings, to € (Euro). The changes will be visible immediately.
4.19. Viewing help: help
Open a browser window that accesses an offline copy of this user guide.
Format: help
4.20. Clearing all entries: clear
Clears all entries from the coupon stash.
Format: clear
4.21. Exiting the program: exit
Exits the program.
Format: exit
4.22. Reminding of coupon expiry
By default, all added coupons have a remind date that is 3 days before its stated expiry date. This default value can be changed during the process of adding a new coupon or by editing an existing coupon. The remind dates for all coupons are checked on program launch. All coupons that have a remind date which falls on the date of program launch will be listed in a popup window on launch. The popup window can be closed by pressing Ctrl + q.
|
Warning
|
Remind dates are only checked during program launch. Thus, if a day passes while the program is open, even if there are coupons expiring on the new day, no new reminder window will open |
As of now, there is no functionality for the disabling of reminders for coupons. This feature will be made available in version 2.0.
-
The format of dates entered via the
r/field is in the D-M-YYYY format. (Coupon Stash date format)
Examples:
-
add n/McDonald’s McGriddles p/ILOVEMCGRIDDLES e/31-12-2020 s/$2 sd/1-4-2020 l/2 t/value t/savouryAdd a new Coupon without specifying a remind date. Note that the default remind date is 3 days before the state expiry date:
-
add n/Grabfood s/40% e/30-4-2020 p/GRAB40 t/delivery r/10-4-2020Add a new Coupon while specifying a remind date of
10-4-2020:
-
edit 1 r/10-4-2020Edit the coupon at index 1 and change its remind date to
10-4-2020.
4.23. Saving the data
Coupon data is saved in the hard disk automatically after any command that changes the data.
There is no need to save manually.
5. Keyboard Shortcuts
With Coupon Stash being optimized for efficient command line usage, how can we not include some nifty keyboard shortcuts to further streamline your workflow! This section introduces some of the keyboard shortcuts available for use in this program.
5.1. Restore previously entered command texts: ↑ and ↓
Pressing the ↑ keyboard button while the focus is on the command box allows you to restore the text of the previous executed command. Pressing the ↓ keyboard button allows you to revert to a more recently entered command.
Demonstration:
5.2. Close expanded coupon or reminder windows: Ctrl+q
After expanding a coupon, you can close
the expanded coupon window by keeping the focus on the coupon window and
pressing the keyboard buttons Ctrl and q simultaneously. This
shortcut also works for closing reminder
windows.
Demonstration:
5.3. Cycle through tabs: Ctrl+Tab
You can press the keyboard buttons Ctrl and Tab simultaneously to switch tabs. Do note that the focus has to be on the main panel before the key presses would work.
Demonstration:
6. FAQ
Q: How do I transfer my data to another computer?
A: Simply install Stash in the other computer and overwrite the empty data
file with your intended data file.
Q: Can I add multiple coupons using a command line?
A: Sorry, not at the moment. We may consider adding this feature in version
2.0.0.
Q : Why do I need to tag my coupons?
A : Tagging is not compulsory. However, it allows you to group similar
coupons together for easier execution. For example, you can easily
delete all the coupons that are tagged, cheap. Do refer to section 4
for more detail.
Q : How do I store coupons with no ending date?
A : Sorry, at the moment, coupon entries with no ending date cannot be
stored. You would need to enter a much further date like 1-1-2030. To
be added in version 2.0.0
Q : How do you calculate the savings value?
A : Whenever a coupon is marked as done, Stash will automatically
calculate the values saved based on the details of the coupon.
7. Command Summary
This section has a summary of all the commands.
| Action | Format |
|---|---|
Add |
|
Edit |
|
Delete |
|
List |
|
Find |
|
Sort |
|
Expiring |
|
Used |
|
Saved |
saved d/DATE_TO_TRACK_FROM |
Archive |
|
Unarchive |
|
Copy |
|
Share |
|
Undo |
|
Redo |
|
Goto |
|
Expand |
|
SetCurrency |
|
Help |
|
Clear |
|
Exit |
|
8. Appendix
8.1. Query expressions (coming in v2.0)
Query expressions serve to enable users to perform efficient batch operations on stored coupons using SQL-like syntax.
Examples:
-
edit favorites set tag=hated where expiry < 19-2-2020
For all coupons tagged asfavorites'', set their tag tohated'' if they expire before the 19th Feb 2020. -
delete favorites where expiry < 19-2-2020
For all coupons tagged as ``favorites'', delete them if they expire before the 19th Feb 2020.
8.1.1. Bulk edit
Format: edit tag set field1=value1, field2=value2, … [where
condition]
-
The
editkeyword is compulsory.-
If selecting all tags, put tag as
*.
-
-
The
setkeyword is compulsory.-
If the field is present in a coupon, update the value, else create the field and value.
-
At least 1 field must be updated/added per edit operation.
-
-
The
wherekeyword is optional.-
The
==,>=,⇐,>,<,!=, operators are supported in the condition. -
Only default fields can be compared.
-
Condition syntax:
DEFAULT_FIELD operator LITERAL_VALUE -
AND/ORfunctionality is not available.
-
8.1.2. Bulk delete
Format: delete tag [where condition]
-
The
deletekeyword is compulsory.-
If selecting all tags, put tag as
*.
-
-
The
wherekeyword is optional.-
If the
wherekeyword is omitted, deletes all coupons with that tag. -
Follows syntax explained above.
-